Skip to main content

Developer Quickstart Guide: Business Connector

Introduction​

The Business Connector is a server-side application, designed to act as an intermediary between the client-side SDK and backend services. It manages the core workflows for issuing, verifying, and managing digital credentials, as well as interacting with agents and external systems. In this guide, we'll walk through the essential setup and workflows involved in using the Business Connector, helping you quickly integrate and deploy it within your environment.

What You’ll Learn​

This guide will cover the following key areas:

  1. Issuing Credentials: A step-by-step guide on issuing credentials, including required endpoints, data structures, and sample requests.
  2. Verifying Credentials: Instructions on handling verification requests, interpreting responses, and maintaining verification records.
  3. Managing Agents: How to interact with agents using the Business Connector, covering agent setup, data flow, and API calls.
  4. Handling Notifications and Events: Overview of setting up and managing notifications, ensuring real-time updates between the server and client.

By the end of this guide, you’ll be able to configure, manage, and utilize the Business Connector to support credential management workflows efficiently.

Table of Contents​

Here’s the organized table of contents with each section linked to its corresponding title:

  1. Authentication and Access Control
  2. Credential Issuance
  3. Request Data from user
  4. Workflow Link Creation (URL and QR Code)

Authentication and Access Control​

To access the admin APIs, a secret key is required. This key is generated in the Business Studio and can be updated as needed. For each request to these APIs, the secret key must be included in the request headers to ensure proper authentication. These APIs incorporate authentication measures and are designed for use within business logic applications, allowing secure and controlled access to core functionalities.

Note: Always keep your secret key secure. Do not expose it in client-side applications or share it publicly. Regularly rotate or regenerate the key as part of your security practices.

By ensuring that each admin API request includes the correct secret key in the headers, you maintain secure communication between your business logic applications and the Business Connector, preventing unauthorized access to sensitive operations like credential issuance and management.

Understanding the Schema​

Before issuing a credential, it is essential to have a schema in place. In the context of credential management, a schema acts as a blueprint that defines the structure and attributes of the data within a credential. Each schema specifies the required fields, data types, and format that the credential must follow, ensuring consistency and validity when the credential is issued or verified.

For instance, a schema for a driver’s license credential might include attributes like:

  • Full Name
  • Date of Birth
  • License Number
  • Expiry Date

Each attribute is specified with a data type (e.g., string, date) and rules, allowing both the issuer and verifier to handle the credential with confidence.

Note: The schema is typically created and managed within an administrative interface of studio, which generates a unique schema ID. Once a schema is created, this ID is used to issue credentials based on its structure.

Issuing a Credential by Agent Alias​

The Business Connector also provides a way to issue a credential based on an agent alias instead of a direct agent ID. This feature is useful when working with preconfigured aliases to identify specific agents within the system, allowing credentials to be issued without needing an explicit agent ID each time.

The endpoint for issuing a credential by alias is:

POST /bc/admin/credential/issue/byalias

This endpoint uses the IssueCredentialByAlias payload to specify the alias, credential details, and the attributes to be included in the credential.

Request Payload Structure​

The payload allows you to issue credentials to a specific agent identified by an alias, and you may issue one offer with multiple credential in it.

The request defines the following properties:

  • agentAlias: (Required) A string alias for the agent receiving the credential. This alias identifies the target agent within the system and must be URL encoded.

    Read more about the format here.

  • requestId: (Optional) A unique identifier for this request, useful for correlating responses.

  • expiryDate: (Optional) The expiration date for the request. Must be in ISO 8601 format (e.g., 2024-12-31T23:59:59Z).

  • payload: Defines the structure and details of the data request, including schemas, formats, and attributes required for the credential.

Read more about the payload structure here

Example Requests​

The API documentation provides examples for issuing different types of credentials, such as W3C Credential, SD-JWT Credential.

W3C Credential Example

{
  "agentAlias": "default:ap1",
  "payload": [
    {
      "schemaId": "https://137.dev-one37.id/bc/public/schemas/com.one37id.email/1.0",
      "format": "w3c",
      "attributes": [
        { "key": "_label", "value": "Verified Email" },
        { "key": "_namespace", "value": "personal.contact.verifiedemail" },
        { "key": "_type", "value": "Email" },
        { "key": "_category", "value": "ContactInformation" },
        { "key": "_trustlevel", "value": "2" },
        { "key": "email", "value": "test@sample.com" }
      ]
    }
  ]
}

SD-JWT Credential Example

{
  "agentAlias": "default:ap1",
  "payload": [
    {
      "schemaId": "https://137.dev-one37.id/bc/public/schemas/com.one37id.email/1.0",
      "format": "sd-jwt",
      "attributes": [
        { "key": "_label", "value": "Verified Email" },
        { "key": "_namespace", "value": "personal.contact.verifiedemail" },
        { "key": "_type", "value": "Email" },
        { "key": "_category", "value": "ContactInformation" },
        { "key": "_trustlevel", "value": "2" },
        { "key": "email", "value": "test@sample.com" }
      ]
    }
  ]
}

Expected Response​

Upon a successful credential issuance, the API returns a response with details about the issued credential.

Example Response​
{
  "isSuccessfull": true,
  "result": {
    "workflowId": "workflow-uuid-1234-5678-90ab",
    "credentials": [
      {
        "credentialId": "cred-uuid-1234",
        "schemaId": "string",
        "namespace": "string"
      }
    ],
    "isWaitingOnConnection": true
  }
}
  • workflowId: Unique identifier for the credential issuance workflow.
  • credentials: Contains details about the issued credential.
  • isWaitingOnConnection: Indicates whether the issuance is pending due to a required connection.

Issuing a Credential by ID​

Once the schema has been created and its ID is available, you can proceed with issuing a credential by making an API call to the Business Connector. This involves using the /issue/byid endpoint, which requires a specific payload to define the credential attributes, schema, and recipient agent.

The endpoint for issuing a credential is:

POST /bc/admin/credential/issue/byid

This endpoint expects a structured request payload that includes information about the schema, expiration date, credential format, and attribute data.

Request Payload Structure​

The payload allows you to issue credentials to a specific agent identified by an alias, and you may issue one offer with multiple credential in it.

The request defines the following properties:

  • agentId: (Required) The ID of the agent to whom the credential request is being sent.

  • requestId: (Optional) A unique identifier for this request, useful for correlating responses.

  • expiryDate: (Optional) The expiration date for the request. Must be in ISO 8601 format (e.g., 2024-12-31T23:59:59Z).

  • payload: Defines the structure and details of the data request, including schemas, formats, and attributes required for the credential.

Read more about the payload structure here

Here’s how the payload is structured:

{
  "agentId": "56942bf9-58c9-4d86-8f0f-00a81425646b",
  "payload": [
    {
      "schemaId": "https://137.dev-one37.id/bc/public/schemas/com.one37id.email/1.0",
      "format": "w3c",
      "attributes": [
        { "key": "_label", "value": "Verified Email" },
        { "key": "_namespace", "value": "personal.contact.verifiedemail" },
        { "key": "_type", "value": "Email" },
        { "key": "_category", "value": "ContactInformation" },
        { "key": "_trustlevel", "value": "2" },
        { "key": "email", "value": "test@sample.com" }
      ]
    }
  ]
}

Example Request​

Here’s an example HTTP request to issue a credential:

POST /bc/admin/credential/issue/byid
Content-Type: application/json

{
  "agentId": "56942bf9-58c9-4d86-8f0f-00a81425646b",
  "requestId": "req-123456",
  "expiryDate": "2025-12-31T23:59:59Z",
  "payload": [
    {
      "schemaId": "schema-uuid-1234-5678-90ab",
      "expirationDate": "2025-12-31T23:59:59Z",
      "format": "w3c",
      "attributes": [
        {
          "key": "fullName",
          "value": "Alice Smith",
        },
        {
          "key": "dateOfBirth",
          "value": "1985-07-10",
        },
        {
          "key": "licenseNumber",
          "value": "D2345678",
        },
        {
          "key": "expiryDate",
          "value": "2025-12-31",
        }
      ]
    }
  ]
}

Expected Response​

On a successful credential issuance, the API returns a response containing the workflow ID and information about the issued credential.

Example Response​
{
  "isSuccessfull": true,
  "result": {
    "workflowId": "string",
    "credentials": [
      {
        "credentialId": "string",
        "schemaId": "string",
        "namespace": "string"
      }
    ],
    "notification": {
      "isRequired": true,
      "payload": {}
    }
  }
}
  • workflowId: A unique identifier for the issuance workflow, which can be used for tracking.
  • credentials: Contains an array with details of the issued credential.
  • notification: An optional field providing additional information about the issuance status.

Connectionless Credential Offer (with URL and QR Code Options)​

The Connectionless Credential Offer enables organizations to issue credentials to users without establishing an ongoing connection. This method is useful for scenarios where credentials need to be delivered through a one-time interaction, such as membership cards, certificates, or digital identity credentials.

The connectionless flow supports two delivery methods:

  1. Using a URL - Generates a link that users can follow to accept the credential offer.
  2. Using a QR Code - Generates a QR code that users can scan to access the offer.

Endpoints​

URL-Based Credential Offer​

POST /bc/admin/credential/create/connectionless

Description​

This endpoint generates a connectionless credential offer by creating a unique URL. The URL can then be shared with the user to accept the offer.

Request Payload​

The payload consists of key properties that define the offer, the credentials being issued, and optional metadata.

{
  "requestId": "unique-request-id",
  "expiryDate": "2024-12-31T23:59:59Z",
  "payload": [
    {
      "schemaId": "https://example.com/schemas/credential/1.0",
      "expirationDate": "2025-01-01T00:00:00Z",
      "format": "w3c",
      "attributes": [
        {
          "key": "email",
          "value": "user@example.com"
        },
        {
          "key": "name",
          "value": "John Doe"
        }
      ]
    }
  ]
}

Response​

{
  "isSuccessfull": true,
  "result": {
    "workflowId": "workflow-123",
    "url": "https://example.com/credential/offer/workflow-123"
  }
}

QR Code-Based Credential Offer​

POST /bc/admin/credential/create/connectionless/qrcode

Description​

This endpoint generates a connectionless credential offer as a QR code. The QR code can be shared with the user, who can scan it to accept the offer. The QR code is returned in PNG format as an attachment.

Request Payload​

The payload format is identical to the URL-based offer request.

Example Request​

{
  "requestId": "unique-request-id",
  "expiryDate": "2024-12-31T23:59:59Z",
  "payload": [
    {
      "schemaId": "https://example.com/schemas/credential/1.0",
      "expirationDate": "2025-01-01T00:00:00Z",
      "format": "W3C",
      "attributes": [
        {
          "key": "email",
          "value": "user@example.com"
        },
        {
          "key": "name",
          "value": "John Doe"
        }
      ]
    }
  ]
}

Example Response​

The response returns a PNG image containing the QR code.

  • Response Headers:
Content-Type: image/png
Content-Disposition: attachment; filename="qr.png"
  • Response Body: Binary PNG data representing the QR code.

Field Descriptions​

  1. requestId: An optional unique identifier for tracking the credential offer request. This is useful for correlating responses with their original requests.

  2. expiryDate: Specifies the expiration date and time of the credential offer. The date should be in ISO 8601 format (e.g., "2024-12-31T23:59:59Z"). This field is optional.

  3. payload: An array containing the details of the credentials being issued. Each element in the array represents one credential and includes the following fields:

    • schemaId: The unique identifier for the credential schema. This field defines the type of credential being issued.
    • expirationDate: The optional expiration date for the specific credential in ISO 8601 format (e.g., "2025-01-01T00:00:00Z").
    • format: Specifies the format of the credential, such as W3C. This field is optional and defaults to W3C.
    • attributes: A list of attributes included in the credential. Each attribute consists of:
      • key: The name of the attribute (e.g., "email").
      • value: The value of the attribute (e.g., "user@example.com"). This field is optional.

Summary​

The Connectionless Credential Offer is a versatile solution for issuing credentials through a one-time interaction. Whether delivered via URL or QR code, this method ensures accessibility and convenience for users while allowing organizations to issue multiple credentials in a single offer.

Request Data from User​

This document describes how to request data from a user securely and efficiently through three methods: By Alias, By ID, and Connectionless. These methods allow organizations to gather required information from users by specifying credentials, attributes, and restrictions.

Sections​

  1. By Alias
  2. By ID
  3. Connectionless

By Alias​

The Request Data by Alias API enables organizations to request data from a user identified by an agent alias. If no connection exists, it will be established before processing the data request.

Endpoint​

POST /bc/admin/proofrequest/send/byalias

Description​

This endpoint sends a data request to a user identified by their alias. The request specifies credentials, their attributes, and restrictions.

Request Payload​

{
  "agentAlias": "default:ap1",
  "protocol": "oid4vp",
  "metadata": {
    "ip": "192.168.0.1",
    "bfphash": "trusted_browser_hash"
  },
  "payload": {
    "name": "Provide email to complete flow.",
    "credentials": [
      {
        "format": "w3c",
        "name": "W3C Verified Email",
        "restrictions": {
          "schemaId": "https://137.dev-one37.id/bc/public/schemas/com.one37id.email/1.0",
          "attributes": [
            {
              "key": "_namespace",
              "value": "personal.contact.verifiedemail"
            }
          ]
        },
        "attributes": [
          {
            "name": "email",
            "isRequired": true
          }
        ]
      }
    ]
  }
}

Field Descriptions​

  1. agentAlias: A string representing the alias of the agent to whom the data request is being sent. This alias uniquely identifies the target agent.

Read more about the format here .

  1. protocol: An optional string indicating the protocol type for the request. Supported values include oid4vp and didcomm, with the default being oid4vp if not specified.
  2. metadata: An optional key-value record providing additional context for the request. Common metadata fields include:
    • ip: Refers to the IP address of the requester, which can provide information about the origin of the request.
    • bfphash: A hashed value that may represent a unique identifier or token associated with the request, ensuring security and traceability.

Read more about ip and bfphash here.

  1. payload: An object containing the details of the request, including the types of credentials being requested and their associated attributes.

Read more about payload object here

By ID​

The Request Data by ID API works similarly to the By Alias method but identifies the user using their agent ID instead of an alias.

Endpoint​

POST /bc/admin/proofrequest/send/byid

Description​

This endpoint sends a data request to a user identified by their agent ID. The request specifies credentials, their attributes, and restrictions.

Request Payload​

{
  "agentId": "123456",
  "protocol": "oid4vp",
  "metadata": {
    "ip": "192.168.0.1",
    "bfphash": "trusted_browser_hash"
  },
  "payload": {
    "name": "Provide email to complete flow.",
    "credentials": [
      {
        "format": "w3c",
        "name": "W3C Verified Email",
        "restrictions": {
          "schemaId": "https://137.dev-one37.id/bc/public/schemas/com.one37id.email/1.0",
          "attributes": [
            {
              "key": "_namespace",
              "value": "personal.contact.verifiedemail"
            }
          ]
        },
        "attributes": [
          {
            "name": "email",
            "isRequired": true
          }
        ]
      }
    ]
  }
}

Field Descriptions​

  1. agentId: A string representing the ID of the agent to whom the data request is being sent. This ID uniquely identifies the target agent.
  2. protocol: An optional string indicating the protocol type for the request. Supported values include oid4vp and didcomm, with the default being oid4vp if not specified.
  3. metadata: An optional key-value record providing additional context for the request. Common metadata fields include:
    • ip: Refers to the IP address of the requester, which can provide information about the origin of the request.
    • bfphash: A hashed value that may represent a unique identifier or token associated with the request, ensuring security and traceability.

Read more about ip and bfphash here .

  1. payload: An object containing the details of the request, including the types of credentials being requested and their associated attributes.

Read more about payload object here

Connectionless​

The Connectionless Data Request API generates a request in the form of a QR code or URL that allows the user to respond without establishing a persistent connection.

Endpoint​

POST /bc/admin/proofrequest/create/connectionless

Description​

This endpoint builds a connectionless data request and returns a QR code image or URL. Users can scan the QR code or visit the URL to respond to the data request.

Request Payload​

{
  "requestId": "unique-request-id",
  "protocol": "oid4vp",
  "expiryDate": "2024-11-08T10:58:11.203Z",
  "metadata": {
    "ip": "192.168.0.1",
    "bfphash": "trusted_browser_hash"
  },
  "payload": {
    "name": "Provide Driver's License",
    "credentials": [
      {
        "format": "w3c",
        "name": "Driver's License",
        "restrictions": {
          "schemaId": "https://example.com/schemas/driver_license",
          "issuerDid": "did:example:123456"
        },
        "attributes": [{ "name": "license_number", "isRequired": true }]
      }
    ]
  }
}

Field Descriptions​

  1. requestId: A unique identifier for tracking the request.
  2. protocol: An optional string indicating the protocol type for the request. Supported values include oid4vp and didcomm, with the default being oid4vp if not specified.
  3. expiryDate: An optional date and time specifying when the data request expires.
  4. metadata: An optional key-value record providing additional context for the request. Common metadata fields include:
    • ip: Refers to the IP address of the requester, which can provide information about the origin of the request.
    • bfphash: A hashed value that may represent a unique identifier or token associated with the request, ensuring security and traceability.

Read more about ip and bfphash here.

  1. payload: An object containing the details of the request, including the types of credentials being requested and their associated attributes.

Read more about payload object here

Summary​

This sections outlines three methods to request data from users securely:

  1. By Alias: Request data by specifying an agent alias.
  2. By ID: Request data by specifying an agent ID.
  3. Connectionless: Request data through a QR code or URL without needing a persistent connection.

Each method ensures flexibility and security in scenarios where user data is required for verification or validation purposes.

These endpoints facilitate triggering server-side workflows from the wallet by generating a unique URL or QR code. These URLs or QR codes act as entry points to initiate workflows on the server, allowing the user to start a specific workflow process with just a click or scan. Such workflows can include actions like identity verification or task processing, enhancing interaction without the need for a long-term connection.

Endpoints​

  1. Generate a Workflow URL: Creates a unique URL that can be shared with users to trigger the specified workflow.
  2. Generate a QR Code for Workflow: Produces a QR code image that encodes the workflow URL, allowing users to scan and initiate the workflow.
POST /bc/admin/flow/url

Description​

This endpoint generates a URL for initiating a server-side workflow based on the specified parameters. Users can click this URL to trigger the associated workflow without needing a persistent connection.

Request Payload​

To utilize this endpoint, submit a JSON payload.

  • Request Example:

    {
      "workflow": "verifyIdentity",
      "methodName": "validateDocument",
      "isConnectionRequired": true,
      "expiryDate": "2024-12-01T10:00:00Z",
      "goal": "Identity verification",
      "parameters": {}
    }

Field Descriptions​

  1. workflow A string specifying the name of the predefined workflow to be initiated. This is the main process or action that the user will engage with.

  2. methodName An optional string indicating a specific method within the workflow to execute. If not provided, the default method for the workflow is used.

  3. isConnectionRequired An optional boolean that specifies whether an agency connection is required before initiating the workflow. The default value is false, meaning the process can proceed without a connection unless explicitly stated.

  4. expiryDate An optional date defining the expiration of the workflow link. Once this date is reached, the link becomes inactive, ensuring time-bound usability.

  5. goal An optional string describing the purpose or goal of the workflow. This description is displayed to the user to provide clarity about the process.

  6. parameters An optional record of key-value pairs that provide additional parameters for the workflow. These parameters allow customization or passing of specific data required during the process.

Response​

If successful, the API responds with a URL string that users can visit to initiate the workflow.

  • Response Example:

    {
      "isSuccessfull": true,
      "result": "https://example.com/bc/admin/flow/url/workflow-123"
    }
POST /bc/admin/flow/qrcode

This endpoint generates a QR code that encodes the workflow URL, allowing users to scan the QR code to initiate the specified workflow.

Request Payload​

The request payload structure for the QR code endpoint is identical to that of the URL generation endpoint.

  • Request Example:

    {
      "workflow": "membershipCheck",
      "methodName": "verifyMember",
      "isConnectionRequired": false,
      "expiryDate": "2024-11-30T18:30:00Z",
      "goal": "Membership verification",
      "parameters": {}
    }

Response​

If the request is successful, the API responds with a QR code image in PNG format. The QR code can be downloaded, shared, or displayed for users to scan directly.

  • Headers:
    • Content-Type: image/png
    • Content-Disposition: attachment; filename="qr.png"

Summary​

The Workflow Link Creation endpoints provide flexible options to trigger workflows server-side:

  • URL Generation: Shareable link that users can click to initiate a workflow.
  • QR Code Generation: Scannable QR code for workflows, ideal for in-person verification or self-service stations.
X

Graph View